FE-1581: Share the optimizer's Optuna study logic in a pure Python core library - #9514

Summary

Before this PR, the optimizer service in apps/petrinaut-opt held the whole Optuna study logic inside PetrinautOptimizer: description checks, sampler construction, parameter suggestion and the study.optimize driver, next to FastAPI, OpenTelemetry and the subprocess bindings. Nothing else could run that study logic. An optimizer that runs where the simulations run, in the browser, would have had to copy it.

This PR moves the study logic into a pure Python library, @local/petrinaut-optimizer-core, and makes the service depend on it. Library builds the seeded study, maps parameter descriptors to suggestions, produces trial events and summaries, and drives a study by ask and tell against an async evaluator. It keeps a study alive across segments so a host can stop it and continue it on the same sampler history, and it keeps several trials in flight when asked. No threads, OS or network calls, so the same modules load under Pyodide. Service behaviour is unchanged.

Links

• Ticket FE-1581

Changes

Python core library

• libs/@local/petrinaut-optimizer-core holds the study logic as one module per concept

  description.py parses and checks a describe result, study.py builds the study and suggests values, ask_tell.py runs a study against an async evaluator, pyodide_entry.py adapts JavaScript callbacks.

• parse_description accepts the CLI's optimization.describe JSON and enforces the service's rules with the same messages

  Sampler set, trial cap, seed sign, duplicate identifiers, finite bounds, log-scale domains and integer log steps.

• run_study asks, awaits the evaluator, tells, and reports each trial with the running best

  An evaluator result of {"objective": x} completes the trial, {"pruned": reason} prunes it, a non-finite objective raises.
  Cancellation is read before each ask and after each evaluate.

• run_study continues a study and keeps several trials in flight

  trials overrides the description's count and continues the same study, so numbering and sampler history carry on.
  Up to parallelism trials run as asyncio tasks and are told in completion order.
  Summary counts are cumulative over the study.

• Stop tells the trials in flight as failed

  No trial stays in Optuna's running state, so a continued study samples from told trials only.

• create_study scales the TPE sampler's random start-up to the study

  Optuna's default of 10 random trials is most of a short study, so no step was ever proposed from results.
  The start-up is now a third of the requested trials, at least 2 and at most 10; an explicit n_startup_trials still wins.

• create_study turns on the constant-liar TPE when a study runs trials in parallel

  Pending trials count as the worst value seen while their evaluation is out, so parallel asks spread instead of repeating.

• Browser entry keeps a study handle across calls

  create_browser_study builds the study once and returns a StudyHandle.
  run_browser_study runs one segment of trials on the handle and adds them to handle.requested.
  release_browser_study drops the study.
  A stopped segment drops its untold remainder from handle.requested, so a stop at 4 of 8 followed by 4 more reads 8 of 8.

• runtime-lock.json pins the Pyodide, Python, Optuna and colorlog versions the browser installs

  A test asserts the pinned Optuna and colorlog versions match the library's own lockfile.

Service

• PetrinautOptimizer delegates description parsing, study creation and suggestion to the core library

  Its threaded study.optimize driver, trial frames, event pump and telemetry stay as they were.

• Service dependency on petrinaut-optimizer-core as an editable path source; Optuna bound to >=4.9,<5

  Dockerfile copies the library before uv sync, the deploy workflow's image path filter includes it, turbo codegen inputs include its sources.

Architecture

• New layer optimizer-core declared on the package and registered in the architecture config
• apps/petrinaut-opt README and AGENTS name the shared library

Test coverage

• libs/@local/petrinaut-optimizer-core/tests:

  Each description rule, suggest mapping per parameter type, seeded determinism, trial event and summary shapes, ask and tell with objectives, pruned outcomes, non-finite rejection, cancellation at both checkpoints, and lockfile parity.

• tests/test_ask_tell.py continuation and parallelism:

  Parallelism 1 gives the same sequence as a plain ask and tell loop.
  A 10-trial study continued by 5 equals a 15-trial study, while a restart repeats the sampler's start-up draws.
  Parallel asks run ahead and are told in completion order, a stop tells the trials in flight as failed and a continuation carries their count, an evaluator error cancels the other tasks.

• tests/test_study.py start-up trials:

  The scaled count per study size, an explicit count winning, the random sampler untouched, and a 6-trial TPE study whose third proposal depends on the objectives told.

• tests/test_pyodide_entry.py:

  Continued numbering and cumulative counts on one handle, stop then continue, release, one segment at a time, trial cap across segments, parallelism reaching the sampler, proxy unwrapping, description and outcome rejection.

• apps/petrinaut-opt/tests:

  Existing service suite; the moved suggest and determinism tests now live in the library.

How to test

• cd libs/@local/petrinaut-optimizer-core && uv sync && uv run pytest
• cd apps/petrinaut-opt && uv sync && uv run pytest

  Expect both suites green and openapi/openapi.json unchanged after yarn codegen